<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Example
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot039.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot036.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc70">7.4</A>&nbsp;&nbsp;Example</H2>
Here we present a simple example use of the Tcl peer multitasking
facilities. The full programs (Tcl and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code) are available in
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> distribution as <TT>example_multi.ecl</TT> and <TT>example_multi.tcl</TT>.<BR>
<BR>
The Tcl program uses the remote Tcl peer interface to create a window that
interacts with the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process it is attached to. Multiple copies of
the program can be run, and attached to the same ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process with a
different remote peer. Each window has three buttons:
<UL CLASS="itemize"><LI CLASS="li-itemize">
run: a button to send an ERPC goal to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> (in this case a simple
 writeln with the peer name;
<LI CLASS="li-itemize">end: a button to end interaction with ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and return control
 to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>;
<LI CLASS="li-itemize">reg: a button to toggle the registration/deregistration of the peer
 for peer multitasking;
</UL>
The program interacts with ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> when the run button is pressed. This
can be done either during a peer multitasking phase, or when the program's specific
peer is given control on its own. When the peer is given control on its
own, only it can interact with ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>; while during peer multitasking,
all the multitasking peers (the copies of the program that are running) can
interact with ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, i.e. the run buttons in all the windows can all
be pressed. <BR>
<BR>
After attaching to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> with <B>ec_remote_init</B>, the program sets
various handlers for the handing of control between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and itself
with <B>ec_running_set_commands</B>: 
<PRE CLASS="verbatim">

ec_running_set_commands ec_start ec_end {} disable_buttons

</PRE>
The handlers for when control is handed back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, <TT>ec_start</TT>,
and when control is handed over from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, <TT>ec_end</TT>, are defined
thus: 
<PRE CLASS="verbatim">

proc ec_end {} {
    if {[ec_multi:get_multi_status] != "on"} {
        enable_buttons
    }
}

proc ec_start {} {
    if {[ec_multi:get_multi_status] != "on"} {
        disable_buttons
    }
}

</PRE>
<TT>enable_buttons</TT> and <TT>disable_buttons</TT> enables and disables the
buttons for the window, respectively. The code tests if the peer is
multitasking with <TT>ec_multi:get_multi_status</TT>. This is needed because
during a peer multitasking phase, control is repeatedly handed back and
forth, and we don't want the buttons to be repeatedly enabled and disabled
during this phase.<BR>
<BR>
Next, the program registers the peer for peer multitasking:
<PRE CLASS="verbatim">

    ec_multi:peer_register [list start multi_start_handler \
                            interact multi_interact_handler]

</PRE>
No special handler is
needed for the end of multitasking, as no special action is needed beyond
disabling the buttons. The return code is stored in a global variable <TT>return_code</TT>. The start handler is defined thus:
<PRE CLASS="verbatim">
proc multi_start_handler {type} {
    global return_code

    if {$type == "demo"} {
        set return_code continue
        enable_buttons
    } else {
        set return_code no
    }
    return $return_code
}
</PRE>
As discussed, multitasking phases can be of different types. For
demonstrating this multitasking features of this example program, the type
is &#8220;demo&#8221;. Therefore the handler tests for this and enables the button if
the phase is &#8220;demo&#8221;. On the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, the multitasking phase is
started with the following predicate call:
<PRE CLASS="verbatim">
        peer_do_multitask(demo),
</PRE>
The interact handler is defined thus:
<PRE CLASS="verbatim">
proc multi_interact_handler {type} {
    global return_code

    if {$return_code == "terminate"} {
            disable_buttons
    }
    return $return_code
</PRE>
The code checks for the two cases where the user has requested to terminate
the multitasking phase by pressing the <TT>.end</TT> button, and disables the
buttons. The end button itself invokes the following code to set <TT>return_code</TT>: 
<PRE CLASS="verbatim">
proc end_interaction {} {
    global return_code
    set return_code terminate
    if {[ec_multi:get_multi_status] != "on"} {
        ec_resume
    }
}
</PRE>
The code checks if it is in a peer multitasking phase, and if so,
<TT>return_code</TT> is set to <TT>terminate</TT>, so that when the handler
returns, the multitasking phase will terminate.
Otherwise, the peer has been explicitly handed control exclusively,
and so control is handed back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> in the normal way using <B>ec_resume</B>.<BR>
<BR>
The program also allows a peer to deregister from multitasking or, if
already deregistered, to register again for multitasking. This is handling
by the following two procedures:
<PRE CLASS="verbatim">
proc register_for_multi {} {
    ec_multi:peer_register [list start multi_start_handler]
    .reg configure  -command {deregister_for_multi}
    .reg configure -text "Deregister multitasking"
}

proc deregister_for_multi {} {
    ec_multi:peer_deregister
    .reg configure  -command {register_for_multi}
    .reg configure -text "Register multitasking"
}
</PRE>
Pressing the <TT>.reg</TT> button will either call <TT>register_for_multi</TT> or
<TT>deregister_for_multi</TT>, depending on if the peer is currently
deregistered or registered for peer multitasking (respectively). The
procedure also changes the button to toggle to the other state.<BR>
<BR>
Pressing the button during a peer multitasking phase will remove the peer
from multitasking immediately. If pressed while the peer is given exclusive
control, the peer will not participate in future multitasking phase (unless
it is re-registered). <BR>
<BR>
<HR>
<A HREF="embroot039.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot036.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
